/*
 *    Copyright (c) 2018-2025, lengleng All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 * Neither the name of the pig4cloud.com developer nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 * Author: lengleng (wangiegie@gmail.com)
 */
package com.pig4cloud.pig.admin.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.pig4cloud.pig.admin.api.entity.SysDict;
import com.pig4cloud.pig.common.core.util.R;

/**
 * 数据字典服务接口
 * <p>
 * 提供数据字典的核心业务逻辑处理，包括字典类型的增删改查和缓存同步功能。
 * 字典是系统中重要的基础数据，用于维护系统中的枚举值和配置项
 * </p>
 *
 * @author lengleng
 * @date 2025/05/30
 */
public interface SysDictService extends IService<SysDict> {

	/**
	 * 批量删除字典
	 * <p>
	 * 根据ID列表删除字典类型，同时删除对应的所有字典项。
	 * 删除前会检查字典是否被系统使用，避免影响业务功能
	 * </p>
	 * 
	 * @param ids 要删除的字典ID数组
	 * @return 操作结果，包含成功数量和失败原因
	 */
	R removeDictByIds(Long[] ids);

	/**
	 * 更新字典
	 * <p>
	 * 更新字典类型的基本信息，如名称、描述、备注等。
	 * 字典类型一旦创建，不允许修改字典代码，以保证系统稳定性
	 * </p>
	 * 
	 * @param sysDict 要更新的字典对象，必须包含ID
	 * @return 操作结果，包含成功状态和提示信息
	 */
	R updateDict(SysDict sysDict);

	/**
	 * 同步字典缓存
	 * <p>
	 * 清空所有字典缓存，强制系统重新从数据库加载字典数据。
	 * 通常在字典数据发生重大变更或缓存不一致时使用
	 * </p>
	 * 
	 * @return 操作结果，包含缓存清除状态
	 */
	R syncDictCache();

}
